home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / graphics / gnuplot / contrib / russo / gnuplotio.3 < prev    next >
Encoding:
Text File  |  1992-03-25  |  20.5 KB  |  265 lines
  1.  
  2.  
  3.  
  4.      GGGGNNNNUUUUPPPPLLLLOOOOTTTTIIIIOOOO((((3333LLLL))))   UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((22227777 NNNNoooovvvveeeemmmmbbbbeeeerrrr 1111999999991111))))    GGGGNNNNUUUUPPPPLLLLOOOOTTTTIIIIOOOO((((3333LLLL))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.           openGnuplot, writeGnuplot, readCurveGnuplot,
  10.           readErrorGnuplot, readGnuplot, readCurveHeadGnuplot,
  11.           readCurve2Gnuplot, readCurve3Gnuplot, closeGnuplot -
  12.           interactive access to Gnuplot via pipes
  13.  
  14.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  15.           ####iiiinnnncccclllluuuuddddeeee """"ggggnnnnuuuupppplllloooottttiiiioooo....hhhh""""
  16.  
  17.           GGGGNNNNUUUUPPPPLLLLOOOOTTTT ****ooooppppeeeennnnGGGGnnnnuuuuppppllllooootttt((((ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ggggnnnnuuuupppplllloooottttppppaaaatttthhhh))))
  18.  
  19.           iiiinnnntttt wwwwrrrriiiitttteeeeGGGGnnnnuuuuppppllllooootttt((((GGGGNNNNUUUUPPPPLLLLOOOOTTTT ****ggggpppp,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr ****ccccoooommmmmmmmaaaannnndddd))))
  20.  
  21.           iiiinnnntttt rrrreeeeaaaaddddEEEErrrrrrrroooorrrrGGGGnnnnuuuuppppllllooootttt((((GGGGNNNNUUUUPPPPLLLLOOOOTTTT ****ggggpppp,,,, cccchhhhaaaarrrr ****bbbbuuuuffff,,,, ssssiiiizzzzeeee____tttt nnnn))))
  22.  
  23.           iiiinnnntttt rrrreeeeaaaaddddGGGGnnnnuuuuppppllllooootttt((((GGGGNNNNUUUUPPPPLLLLOOOOTTTT ****ggggpppp,,,, cccchhhhaaaarrrr ****bbbbuuuuffff,,,, ssssiiiizzzzeeee____tttt nnnn))))
  24.  
  25.           GGGGPPPPCCCCuuuurrrrvvvveeee ****rrrreeeeaaaaddddCCCCuuuurrrrvvvveeeeGGGGnnnnuuuuppppllllooootttt((((GGGGNNNNUUUUPPPPLLLLOOOOTTTT ****ggggpppp))))
  26.  
  27.           iiiinnnntttt rrrreeeeaaaaddddCCCCuuuurrrrvvvveeeeHHHHeeeeaaaaddddGGGGnnnnuuuuppppllllooootttt((((GGGGNNNNUUUUPPPPLLLLOOOOTTTT ****ggggpppp,,,, iiiinnnntttt ****ccccuuuurrrrvvvveeeennnnoooo,,,, iiiinnnntttt
  28.           ****nnnnppppttttssss))))
  29.  
  30.           iiiinnnntttt rrrreeeeaaaaddddCCCCuuuurrrrvvvveeee2222GGGGnnnnuuuuppppllllooootttt((((GGGGNNNNUUUUPPPPLLLLOOOOTTTT ****ggggpppp,,,, cccchhhhaaaarrrr ****rrrraaaannnnggggeeee,,,, ffffllllooooaaaatttt ****xxxx,,,,
  31.           ffffllllooooaaaatttt ****yyyy,,,, iiiinnnntttt nnnnppppttttssss))))
  32.  
  33.           iiiinnnntttt rrrreeeeaaaaddddCCCCuuuurrrrvvvveeee3333GGGGnnnnuuuuppppllllooootttt((((GGGGNNNNUUUUPPPPLLLLOOOOTTTT ****ggggpppp,,,, cccchhhhaaaarrrr ****rrrraaaannnnggggeeee,,,, ffffllllooooaaaatttt ****xxxx,,,,
  34.           ffffllllooooaaaatttt ****yyyy,,,, ffffllllooooaaaatttt ****zzzz,,,,iiiinnnntttt nnnnppppttttssss))))
  35.  
  36.           iiiinnnntttt cccclllloooosssseeeeGGGGnnnnuuuuppppllllooootttt((((GGGGNNNNUUUUPPPPLLLLOOOOTTTT ****ggggpppp,,,, iiiinnnntttt qqqquuuuiiiittttffffllllaaaagggg))))
  37.  
  38.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  39.           The ggggnnnnuuuupppplllloooottttiiiioooo library allows an application to run the
  40.           ggggnnnnuuuuppppllllooootttt((((1111LLLL)))) plotting package interactively via UNIX pipes.
  41.           ggggnnnnuuuuppppllllooootttt((((1111LLLL)))) is spawned using a variant of ppppooooppppeeeennnn(3), called
  42.           ppppooooppppeeeennnn____iiiiooooeeee(3L), which opens the ggggnnnnuuuuppppllllooootttt process for writing
  43.           on stdin, and reading on both stdout and stderr.
  44.  
  45.           GGGGeeeennnneeeerrrraaaallll IIIInnnntttteeeerrrraaaaccccttttiiiivvvveeee UUUUsssseeee
  46.           To run ggggnnnnuuuuppppllllooootttt interactively, but under the control of a
  47.           program, only ooooppppeeeennnnGGGGnnnnuuuuppppllllooootttt(((()))), wwwwrrrriiiitttteeeeGGGGnnnnuuuuppppllllooootttt(((()))), rrrreeeeaaaaddddGGGGnnnnuuuuppppllllooootttt(((()))),
  48.           cccclllloooosssseeeeGGGGnnnnuuuuppppllllooootttt(((()))), and perhaps rrrreeeeaaaaddddEEEErrrrrrrroooorrrrGGGGnnnnuuuuppppllllooootttt(((()))) need ever be
  49.           called. The output will appear graphically on whatever
  50.           output device the application chooses to set.
  51.  
  52.           EEEExxxxpppprrrreeeessssssssiiiioooonnnn EEEEvvvvaaaalllluuuuaaaattttoooorrrr
  53.           An application can turn ggggnnnnuuuuppppllllooootttt(1L) into a poor man's
  54.           expression evaluator by setting the terminal type to
  55.           ``table''. Then, instead of plotting a graph of the
  56.           expression in the ``plot _e_x_p_r'' and ``splot _e_x_p_r'' commands,
  57.           ggggnnnnuuuuppppllllooootttt(1L) writes the evaluated X, Y (and in the case of
  58.           splot, Z) values in an ASCII table on its stdout. The
  59.           application can retrieve the samples and do whatever further
  60.  
  61.  
  62.  
  63.      Page 1                                         (printed 12/10/91)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      GGGGNNNNUUUUPPPPLLLLOOOOTTTTIIIIOOOO((((3333LLLL))))   UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((22227777 NNNNoooovvvveeeemmmmbbbbeeeerrrr 1111999999991111))))    GGGGNNNNUUUUPPPPLLLLOOOOTTTTIIIIOOOO((((3333LLLL))))
  71.  
  72.  
  73.  
  74.           processing it wants to, eg. compute the Fourier Transform of
  75.           an analytic function that the user typed in. The sampling
  76.           rate (interval) can be controlled by specifying the number
  77.           of samples and the evaluation interval. For example, the
  78.           following code fragment evaluates the expression at
  79.           intervals of 200 samples/10 sec = 20 samples/sec (or a
  80.           sampling rate of 50 msec).
  81.  
  82.                gp = openGnuplot("");
  83.                writeGnuplot(gp,"set term table");
  84.                writeGnuplot(gp,"set samples 200");
  85.                writeGnuplot(gp,"plot [x=0:9] exp(-.02*x)*sin(x)");
  86.                gc = readCurve(gp);
  87.                closeGnuplot(gp,0);
  88.  
  89.           Thus, for a small additional programming effort, a
  90.           programmer can leverage off the development of ggggnnnnuuuuppppllllooootttt and
  91.           add full-fledged expression evaluation capability to his or
  92.           her application without having to know _anything_ about
  93.           parsing and lexical analysis!
  94.  
  95.           RRRRoooouuuuttttiiiinnnneeee DDDDeeeessssccccrrrriiiippppttttiiiioooonnnnssss
  96.           ooooppppeeeennnnGGGGnnnnuuuuppppllllooootttt(((()))) opens a connection to the ggggnnnnuuuuppppllllooootttt program
  97.           named in _g_n_u_p_l_o_t_p_a_t_h. If it is a NULL pointer or a NULL
  98.           string, ooooppppeeeennnnGGGGnnnnuuuuppppllllooootttt(((()))) will search the user's $PATH (see
  99.           eeeennnnvvvviiiirrrroooonnnn(5)) for the generic program ``gnuplot''.
  100.           ooooppppeeeennnnGGGGnnnnuuuuppppllllooootttt(((()))) will return a GNUPLOT handle after ggggnnnnuuuuppppllllooootttt is
  101.           located, executed, and communications are established;
  102.           otherwise NULL is returned. The handle is unique to that
  103.           communication channel and must be passed to other ggggnnnnuuuupppplllloooottttiiiioooo
  104.           routines. This allows an application to open multiple,
  105.           independent connections to ggggnnnnuuuuppppllllooootttt if it wants to.
  106.  
  107.           wwwwrrrriiiitttteeeeGGGGnnnnuuuuppppllllooootttt(((()))) issues _c_o_m_m_a_n_d to ggggnnnnuuuuppppllllooootttt.  (See ggggnnnnuuuuppppllllooootttt(1L)
  108.           as well as the on-line help for more information on the
  109.           syntax and meaing on ggggnnnnuuuuppppllllooootttt commands.)  The command string
  110.           will be newline-terminated if it doesn't end with a newline
  111.           already. (Gnuplot needs a newline to know when to begin
  112.           interpreting the command, as it reads its input using line
  113.           buffering.)  -1 is returned if _g_p is not a properly
  114.           initialized GNUPLOT handle or the command pointer is NULL.
  115.           Otherwise 1 is returned, indicating success, even though
  116.           there is no absolute guarantee that ggggnnnnuuuuppppllllooootttt got and
  117.           understood the command.
  118.  
  119.           There are several ways to retreive information back from
  120.           ggggnnnnuuuuppppllllooootttt:  rrrreeeeaaaaddddGGGGnnnnuuuuppppllllooootttt(((()))), rrrreeeeaaaaddddCCCCuuuurrrrvvvveeeeGGGGnnnnuuuuppppllllooootttt(((()))),
  121.           rrrreeeeaaaaddddCCCCuuuurrrrvvvveeeeHHHHeeeeaaaaddddGGGGnnnnuuuuppppllllooootttt(((()))), rrrreeeeaaaaddddCCCCuuuurrrrvvvveeee2222GGGGnnnnuuuuppppllllooootttt(((()))),
  122.           rrrreeeeaaaaddddCCCCuuuurrrrvvvveeee3333GGGGnnnnuuuuppppllllooootttt(((()))), rrrreeeeaaaaddddEEEErrrrrrrroooorrrrGGGGnnnnuuuuppppllllooootttt(((()))).  rrrreeeeaaaaddddGGGGnnnnuuuuppppllllooootttt(((())))
  123.           reads one line of output from ggggnnnnuuuuppppllllooootttt and copies the
  124.           characters, without interpretation, into _b_u_f, limited to a
  125.           maximum of _n characters.  rrrreeeeaaaaddddGGGGnnnnuuuuppppllllooootttt(((()))) returns 1 upon
  126.  
  127.  
  128.  
  129.      Page 2                                         (printed 12/10/91)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      GGGGNNNNUUUUPPPPLLLLOOOOTTTTIIIIOOOO((((3333LLLL))))   UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((22227777 NNNNoooovvvveeeemmmmbbbbeeeerrrr 1111999999991111))))    GGGGNNNNUUUUPPPPLLLLOOOOTTTTIIIIOOOO((((3333LLLL))))
  137.  
  138.  
  139.  
  140.           successful read [should return the number of characters
  141.           actually copied into _b_u_f on success], and -1 if any input
  142.           parameters were invalid.  Use this read to get status-type
  143.           information from ggggnnnnuuuuppppllllooootttt,,,, such as the response to a ``show''
  144.           command.  rrrreeeeaaaaddddCCCCuuuurrrrvvvveeeeGGGGnnnnuuuuppppllllooootttt(((()))) completely processes the
  145.           returned data after a ``plot _e_x_p_r'' or a ``splot _e_x_p_r''
  146.           command has been written with wwwwrrrriiiitttteeeeGGGGnnnnuuuuppppllllooootttt(((()))).  A pointer to
  147.           a GPCurve struct is returned on success, which contains
  148.           _n_p_t_s, the number pf points returned, float arrays _x[] and
  149.           _y[] (allocated by mmmmaaaalllllllloooocccc(3) to _n_p_t_s). _r_a_n_g_e[] is a character
  150.           flag array which tells whether each point is inrange,
  151.           (inside the plot bounds), outrange (outside of the plot
  152.           bounds but still defined), or undefined (eg. in the case of
  153.           infinities occurring in the interval over which the
  154.           expression was evaluated).  The flag _i_s__2_d will be TRUE if
  155.           the data is a 2D line plot (``plot'' command) and the _z
  156.           pointer will be NULL. If the curve represents the output
  157.           from a 3D surface plot (``splot'' command), _i_s__2_d will be
  158.           FALSE and _z[] will be allocated just like _x[] and _y[].
  159.  
  160.               typedef struct {
  161.                   unsigned npts;    /* number of points */
  162.                   int is_2d;        /* True: only x,y are valid; z=NULL */
  163.                   int curveno;      /* Curve id number */
  164.                   float *x;         /* x[npts] */
  165.                   float *y;         /* y[npts] */
  166.                   float *z;         /* z[npts] */
  167.                   char *range;      /* range[npts]: 'i' inrange,
  168.                                                     'o' outrange,
  169.                                                     'u' undefined */
  170.               } GPCurve;
  171.  
  172.           If the application writes a plot command requesting more
  173.           than one curve, eg. ``plot sin(x),x*cos(x),bessj0(x)'' then
  174.           the application should call rrrreeeeaaaaddddCCCCuuuurrrrvvvveeeeGGGGnnnnuuuuppppllllooootttt(((()))) as many times
  175.           as necessary to retrieve all the curve data. The _c_u_r_v_e_n_o
  176.           field will be set with curve identifier number (Note: unique
  177.           _o_n_l_y to that specific plot command).  NULL is returned if
  178.           any input parameters are invalid or rrrreeeeaaaaddddCCCCuuuurrrrvvvveeeeGGGGnnnnuuuuppppllllooootttt(((()))) if
  179.           can't mmmmaaaalllllllloooocccc(3) all the space it needs.
  180.  
  181.           cccclllloooosssseeeeGGGGnnnnuuuuppppllllooootttt(((()))) shuts down a connection to ggggnnnnuuuuppppllllooootttt.  If
  182.           _q_u_i_t_f_l_a_g is non-zero, a ``quit'' command will be sent first
  183.           to ggggnnnnuuuuppppllllooootttt to allow for a graceful exit. Then the pipe
  184.           connections will be closed.  A 0 is returned if
  185.           ppppcccclllloooosssseeee____iiiiooooeeee(3L) fails and a 1 for successful close.
  186.  
  187.           The routines rrrreeeeaaaaddddCCCCuuuurrrrvvvveeeeHHHHeeeeaaaaddddGGGGnnnnuuuuppppllllooootttt(((()))), rrrreeeeaaaaddddCCCCuuuurrrrvvvveeee2222GGGGnnnnuuuuppppllllooootttt(((()))),
  188.           and rrrreeeeaaaaddddCCCCuuuurrrrvvvveeee3333GGGGnnnnuuuuppppllllooootttt(((()))) provide the application with more
  189.           control by doing the job of rrrreeeeaaaaddddCCCCuuuurrrrvvvveeeeGGGGnnnnuuuuppppllllooootttt(((()))) in pieces.
  190.           For example, rrrreeeeaaaaddddCCCCuuuurrrrvvvveeeeHHHHeeeeaaaaddddGGGGnnnnuuuuppppllllooootttt(((()))) returns only the curve
  191.           id number and number of points into _c_u_r_v_e_n_o and _n_p_t_s,
  192.  
  193.  
  194.  
  195.      Page 3                                         (printed 12/10/91)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      GGGGNNNNUUUUPPPPLLLLOOOOTTTTIIIIOOOO((((3333LLLL))))   UUUUNNNNIIIIXXXX SSSSyyyysssstttteeeemmmm VVVV ((((22227777 NNNNoooovvvveeeemmmmbbbbeeeerrrr 1111999999991111))))    GGGGNNNNUUUUPPPPLLLLOOOOTTTTIIIIOOOO((((3333LLLL))))
  203.  
  204.  
  205.  
  206.           respectively. The application can then mmmmaaaalllllllloooocccc(3) its own
  207.           arrays and have rrrreeeeaaaaddddCCCCuuuurrrrvvvveeee2222GGGGnnnnuuuuppppllllooootttt(((()))) fill the _r_a_n_g_e, _x, _y
  208.           arrays, in the case of 2D data. For 3D data,
  209.           rrrreeeeaaaaddddCCCCuuuurrrrvvvveeee3333GGGGnnnnuuuuppppllllooootttt(((()))) will fill the _r_a_n_g_e, _x, _y, _z arrays. In
  210.           both routines, if the application doesn't care about the
  211.           range information, pass a NULL pointer for _r_a_n_g_e.
  212.  
  213.           EEEErrrrrrrroooorrrr HHHHaaaannnnddddlllliiiinnnngggg
  214.           If ggggnnnnuuuuppppllllooootttt detects a syntax or other error on the input
  215.           command, it will write an error message on its stderr, which
  216.           the application can fetch with rrrreeeeaaaaddddEEEErrrrrrrroooorrrrGGGGnnnnuuuuppppllllooootttt(((()))).
  217.           rrrreeeeaaaaddddEEEErrrrrrrroooorrrrGGGGnnnnuuuuppppllllooootttt(((()))) uses sssseeeelllleeeecccctttt(2) so it will not block if
  218.           there is no error message to read. The message, if any, is
  219.           copied into _b_u_f and the number of characters copied is
  220.           returned (0 for no message).  Due to latencies involved with
  221.           stdout buffering, an error may not be detected immediately
  222.           after an erroneous command is issued to ggggnnnnuuuuppppllllooootttt.  For
  223.           example, in the sequence
  224.  
  225.                writeGnuplot(gp, "plotte nofunc(a)");
  226.                if(readErrorGnuplot(gp, buf, n) > 0) {
  227.                    /* Error! */
  228.                };
  229.  
  230.           rrrreeeeaaaaddddEEEErrrrrrrroooorrrrGGGGnnnnuuuuppppllllooootttt(((()))) may not report an error. But it will be
  231.           reported by the next call to rrrreeeeaaaaddddEEEErrrrrrrroooorrrrGGGGnnnnuuuuppppllllooootttt(((()))).
  232.  
  233.      RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEESSSS
  234.           Routines that return an int return -1 if the input
  235.           parameters are bad, ie uninitialized GNUPLOT handles, NULL
  236.           pointers for arrays, etc.
  237.  
  238.      SSSSEEEEEEEE AAAALLLLSSSSOOOO
  239.           ggggnnnnuuuuppppllllooootttt(1L), ppppooooppppeeeennnn____iiiiooooeeee(3L)
  240.  
  241.      LLLLIIIIMMMMIIIITTTTAAAATTTTIIIIOOOONNNNSSSS
  242.           Error handling is currently not terribly robust. An
  243.           application using the gnuplotio library should not expect to
  244.           rrrreeeeaaaadddd****GGGGnnnnuuuuppppllllooootttt(((()))) without first issuing a wwwwrrrriiiitttteeeeGGGGnnnnuuuuppppllllooootttt(((()))) call
  245.           that will generate output. Otherwise, the read may block.
  246.  
  247.      CCCCAAAAVVVVEEEEAAAATTTTSSSS
  248.           Your version of gnuplot (version 3.1 or higher) must support
  249.           the ``table'' terminal type to use the expression evaluation
  250.           routines.
  251.  
  252.      AAAAUUUUTTTTHHHHOOOORRRR
  253.           Kevin Russo, SFA, Inc. / US Naval Research Lab, Code 5133
  254.           russo@orion.nrl.navy.mil
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.      Page 4                                         (printed 12/10/91)
  262.  
  263.  
  264.  
  265.